Git Workflows

Introduction

A Git workflow defines how changes move from local work to reviewed and deployable history. The right workflow keeps collaboration predictable without adding unnecessary ceremony.

Purpose

This document covers the most common workflow choices for:

• Application repositories
• Infrastructure-as-code repositories
• Self-hosted service configuration

Architecture Overview

A Git workflow usually combines:

• Branching strategy
• Review policy
• Merge policy
• Release or deployment trigger

The two patterns most teams evaluate first are:

• Trunk-based development with short-lived branches
• Feature branches with pull or merge requests

Common Workflow Patterns

Trunk-based with short-lived branches

Changes are kept small and integrated frequently into the default branch. This works well for active teams, automated test pipelines, and repositories that benefit from continuous deployment.

Longer-lived feature branches

This can be useful for larger changes or teams with less frequent integration, but it increases drift and merge complexity.

Infrastructure repositories

For IaC and self-hosting repos, prefer small reviewed changes with strong defaults:

• Protected main branch
• Required checks before merge
• Clear rollback path
• Commit messages that explain operational impact

Configuration Example

Example daily workflow:

git switch main
git pull --ff-only
git switch -c feature/update-grafana
git add .
git commit -m "Update Grafana image and alert rules"
git push -u origin feature/update-grafana

Before merge:

git fetch origin
git rebase origin/main

Troubleshooting Tips

Merge conflicts happen constantly

• Reduce branch lifetime
• Split large changes into smaller reviewable commits
• Rebase or merge from the default branch more frequently

History becomes hard to audit

• Use meaningful commit messages
• Avoid mixing unrelated infrastructure and application changes in one commit
• Document the operational reason for risky changes in the pull request

Reverts are painful

• Keep commits cohesive
• Avoid squash-merging unrelated fixes together
• Ensure deployments can be tied back to a specific Git revision

Best Practices

• Prefer short-lived branches and small pull requests
• Protect the default branch and require review for shared repos
• Use fast-forward pulls locally to avoid accidental merge noise
• Keep configuration and deployment code in Git, not in ad hoc host edits
• Align the Git workflow with deployment automation instead of treating them as separate processes

References

• Git: gitworkflows
• Pro Git: Branching workflows